Standard Type Input and Output (StdTypIO)(OD Cookbook)

Inside Macintosh: OpenDoc Cookbook / Part - Appendixes: Appendix A - OpenDoc Utilities

Standard Type Input and Output (StdTypIO)
This section describes the utilities defined in the files StdTypIO.h and StdTypIO.cpp. These utilities allow you to manipulate OpenDoc storage units more simply and enable you to read and write various commonly used data types (such as integers, ISO strings, time values, storage unit references, and so forth) in a standard storage format to facilitate document exchange.
The standard type input and output functions are designed to be used independent of property and value type, and in many cases can even be used to manipulate data in the middle of values. To do so, pass in a prefocused storage unit with the offset set correctly, and pass in kODNULL for the ODPropertyName and the ODValueType parameters.

Boolean Values
The following function returns a Boolean value from a storage unit:
ODBoolean ODGetBooleanProp(Environment* ev, 
            ODStorageUnit* su, ODPropertyName prop, ODValueType val)
Short Values
The following functions get and set unsigned and signed 16-bit values:
ODUShort ODGetUShortProp(Environment* ev, 
            ODStorageUnit* su, ODPropertyName prop, ODValueType val)
void  ODSetUShortProp(Environment* ev, 
            ODStorageUnit* su, ODPropertyName prop, ODValueType val,
            ODUShort value)
ODSShort ODGetSShortProp(Environment* ev, 
            ODStorageUnit* su, ODPropertyName prop, ODValueType val)
void  ODSetSShortProp(Environment* ev, 
            ODStorageUnit* su, ODPropertyName prop, ODValueType val,
            ODSShort value)
Long Values
The following functions get and set unsigned and signed 32-bit values:
ODULongODGetULongProp(Environment* ev, 
            ODStorageUnit* su, ODPropertyName prop, ODValueType val)
void  ODSetULongProp(Environment* ev, 
            ODStorageUnit* su, ODPropertyName prop, ODValueType val,
            ODULong value)
ODSLongODGetSLongProp(Environment* ev, 
            ODStorageUnit* su, ODPropertyName prop, ODValueType val)
void  ODSetSLongProp(Environment* ev, 
            ODStorageUnit* su, ODPropertyName prop, ODValueType val,
            ODSLong value)
ISO String Values
An ISO string (ODISOStr) is a string of 7-bit ASCII characters terminated by a zero byte. The functions in this section get and set ISO string values in storage units.
ODISOStr ODGetISOStrProp(Environment* ev, 
            ODStorageUnit* su, ODPropertyName prop, ODValueType val,
            ODISOStr value, ODULong* size)
void  ODSetISOStrProp(Environment* ev, 
            ODStorageUnit* su, ODPropertyName prop, ODValueType val,
            ODISOStr value)
Type List Values
The functions in this section get and set values of type ODTypeList. An ODTypeList property value containing n elements begins with (n+1) offsets, followed by n ISO strings with their null termination. The first n offsets identify the starting positions of the corresponding ISO string. The last offset is always equal to the size of the value and is immediately before the first character of the first ISO string. For example, a property value representing an empty ODTypeList object is 4 bytes long and contains offset four, signifying that there are no ISO strings present.
void ODGetTypeListProp(Environment* ev,
            ODStorageUnit* su, ODPropertyName prop, ODValueType val,
            ODTypeList* typeList)
void ODSetTypeListProp(Environment* ev,
            ODStorageUnit* su, ODPropertyName prop, ODValueType val,
            ODTypeList* typeList)
Text Values
The following functions manipulate international text, Unicode text, and traditional Mac OS text values:
void TradMacTextToUnicode(ODUByte* macText, ODULong macTextLength,
            ODUShort** unicodeText, ODULong* uniCodeBufferLength);
void UnicodeToTradMacText(ODUShort* unicodeText, 
            ODULong uniCodeTextLength,
            ODUByte** macText, ODULong* macTextLength);
ODIText* UnicodeToIText(ODIText* iText, ODUShort* unicodeText,
                  ODULong unicodeTextLength);
In the ODGetITextProp function, if the iText parameter is kODNULL, a variable of type ODIText is allocated and passed back. If not, the _buffer field of the text within the iText structure is deallocated and a new _buffer is allocated and filled. If no value is passed in the ODPropertyName and ODValueType parameters, the function returns kODNULL.
ODIText* ODGetITextProp(Environment* ev, 
            ODStorageUnit* su, ODPropertyName prop, ODValueType val,
            ODIText* iText)
In the ITextToUnicode function, storage passed back must be deallocated with the ODDisposePtr function.
void ITextToUnicode(ODIText* iText, ODUShort** unicodeText,
                  ODULong* unicodeTextLength);
void ODSetITextProp(Environment* ev, 
         ODStorageUnit* su, ODPropertyName prop, ODValueType val,
         ODIText* iText)
Time Values
The following functions get and set values of type ODTime:
ODTimeODGetTime_TProp(Environment* ev, 
            ODStorageUnit* su, ODPropertyName prop, ODValueType val)
void  ODSetTime_TProp(Environment* ev, 
            ODStorageUnit* su, ODPropertyName prop, ODValueType val,
            ODTime value)
Geometric Values
The following functions get and set values of type ODPoint, ODRect, ODPolygon, and ODMatrix:
ODPoint* ODGetPointProp(Environment* ev, 
            ODStorageUnit* su, ODPropertyName prop, ODValueType val,
            ODPoint* value)
void  ODSetPointProp(Environment* ev, 
            ODStorageUnit* su, ODPropertyName prop, ODValueType val,
            ODPoint* value)
ODRect*ODGetRectProp(Environment* ev, 
            ODStorageUnit* su, ODPropertyName prop, ODValueType val,
            ODRect* value)
void  ODSetRectProp(Environment* ev, 
            ODStorageUnit* su, ODPropertyName prop, ODValueType val,
            ODRect* value)
ODPolygon* ODGetPolygonProp(Environment* ev, 
            ODStorageUnit* su, ODPropertyName prop, ODValueType val,
            ODPolygon* value)
void  ODSetPolygonProp(Environment* ev, 
            ODStorageUnit* su, ODPropertyName prop, ODValueType val,
            const ODPolygon* value)
ODMatrix* ODGetMatrixProp(Environment* ev, 
            ODStorageUnit* su, ODPropertyName prop, ODValueType val,
            ODMatrix* value)
void ODSetMatrixProp(Environment* ev, 
            ODStorageUnit* su, ODPropertyName prop, ODValueType val,
            ODMatrix* value)
Storage Unit Reference Values
The following functions get and set strong and weak storage unit references:
ODID  ODGetStrongSURefProp(Environment* ev, 
            ODStorageUnit* su, ODPropertyName prop, ODValueType val)
void  ODSetStrongSURefProp(Environment* ev, 
            ODStorageUnit* su, ODPropertyName prop, ODValueType val,
            ODID id)
ODID  ODGetWeakSURefProp(Environment* ev, 
            ODStorageUnit* su, ODPropertyName prop, ODValueType val)
void  ODSetWeakSURefProp(Environment* ev, 
            ODStorageUnit* su, ODPropertyName prop, ODValueType val,
            ODID id)
Icon Family Values
The functions in this section get and set values of type ODIconFamily. The ODIconFamily type is platform specific, so the functions have platform-specific implementations. The following values are used for the iconMask parameter.
enum {
   kAllIconsMask = 0xFFFFFFFF,// All icons usable on this platform
   kBWIconsMask  = 0x0421// 1 bit deep, 16,32,64 pixels wide
};
Expected values for the ODValueType parameter begin with OpenDoc:Type:IconFamily: followed by the name of a platform. The platform names are defined in StdTypes.idl as kODIconFamilyMac, kODIconFamilyWin, kODIconFamilyOS2, and kODIconFamilyAIX. If you specify only kODIconFamily, the type of the current platform is used.
ODIconFamily ODGetIconFamilyProp(Environment* ev,
               ODStorageUnit* su, ODPropertyName prop, 
               ODValueType val, ODULong iconMask);
void     ODSetIconFamilyProp(Environment* ev,
               ODStorageUnit* su, ODPropertyName prop, 
               ODValueType val, ODIconFamily iconFamily,
               ODBoolean deleteOtherPlatformIcons);